View RH850_8285079.PDF datasheet online --- IC-ON-LINE

Datasheet File OCR Text:

all information contained in these materials, including products and product specifications, represents information on the product at the time of publication and is subject to change by renesas electronics corp. without notice. please review the latest inf ormation published by renesas electronics corp. through various means, including the renesas technology corp. website (http://www.renesas.com). all information contained in these materials, including products and product specifications, represents info rmation on the product at the time of publication and is subject to change by renesas electronics corp. without notice. please review the latest information published by renesas electronics corp. through various means, including the renesas technology corp . website (http://www.renesas.com). r01us0079ed0103 19.02.2014 user manual 32 32 data flash access library type t01, european release renesas 32 - bit mcu rh family / RH850 series installer: renesas_fdl_RH850_t01e_v1.xx ww w .renesa s .com
data flash access library - type t01, european release notice r01us0079ed0103 2 user manual notice all information included in this document is current as of the date this document is issued. such information, 1. however, is subject to change without any prior notice. before purchasing or using any renesas electronics products listed herein, please confirm the latest product information with a renesas electronics sales office. also, please pay regular and careful attention to additional and different information to be disclosed by renesas electronics such as that disclosed through our website. renesas elect ronics does not assume any liability for infringement of patents, copyrights, or other 2. intellectual property rights of third parties by or arising from the use of renesas electronics products or technical information described in this document. no license, express, implied or otherwise, is granted hereby under any patents, copyrights or other intellectual property rights of renesas electronics or others. you should not alter, modify, copy, or otherwise misappropriate any renesas electronics product, whether 3. in whole or in part. descriptions of circuits, software and other related information in this document are provided only to 4. illustrate the operation of semiconductor products and application examples. you are fully responsible for the incorporation of th ese circuits, software, and information in the design of your equipment. renesas electronics assumes no responsibility for any losses incurred by you or third parties arising from the use of these circuits, software, or information. when exporting the pro ducts or technology described in this document, you should comply with the 5. applicable export control laws and regulations and follow the procedures required by such laws and regulations. you should not use renesas electronics products or the technology de scribed in this document for any purpose relating to military applications or use by the military, including but not limited to the development of weapons of mass destruction. renesas electronics products and technology may not be used for or incorporated into any products or systems whose manufacture, use, or sale is prohibited under any applicable domestic or foreign laws or regulations. renesas electronics has used reasonable care in preparing the information included in this document, but 6. renesas elect ronics does not warrant that such information is error free. renesas electronics assumes no liability whatsoever for any damages incurred by you resulting from errors in or omissions from the information included herein. renesas electronics products are c lassified according to the following three quality grades: standard, 7. high quality, and specific. the recommended applications for each renesas electronics product depends on the products quality grade, as indicated below. you must check the quali ty grade of each renesas electronics product before using it in a particular application. you may not use any renesas electronics product for any application categorized as specific without the prior written consent of renesas electronics. further, you may not use any renesas electronics product for any application for which it is not intended without the prior written consent of renesas electronics. renesas electronics shall not be in any way liable for any damages or losses incurred by you or third pa rties arising from the use of any renesas electronics product for an application categorized as specific or for which the product is not intended where you have failed to obtain the prior written consent of renesas electronics.
data flash access library - type t01, european release notice r01us0079ed0103 3 user manual the quality grade of eac h renesas electronics product is standard unless otherwise expressly specified in 8. a renesas electronics data sheets or data books, etc. computers; office equipment; communications equipment; test and measurement equipment; audio and visual eq uipment; home electronic appliances; machine tools; personal electronic equipment; and industrial robots. transportation equipment (automobiles, trains, ships, etc.); traffic control systems; anti - disaster systems; anti - crime systems; safe ty equipment; and medical equipment not specifically designed for life support. aircraft; aerospace equipment; submersible repeaters; nuclear reactor control systems; medical equipment or systems for life support (e.g. artificial life support d evices or systems), surgical implantations, or healthcare intervention (e.g. excision, etc.), and any other applications or purposes that pose a direct threat to human life. you should use the renesas electronics products described in this document within the range specified by 9. renesas electronics, especially with respect to the maximum rating, operating supply voltage range, movement power voltage range, heat radiation characteristics, installation and other product characteristics. renesas electronics sha ll have no liability for malfunctions or damages arising out of the use of renesas electronics products beyond such specified ranges. although renesas electronics endeavours to improve the quality and reliability of its products, 10. semiconductor products hav e specific characteristics such as the occurrence of failure at a certain rate and malfunctions under certain use conditions. further, renesas electronics products are not subject to radiation resistance design. please be sure to implement safety measures to guard them against the possibility of physical injury, and injury or damage caused by fire in the event of the failure of a renesas electronics product, such as safety design for hardware and software including but not limited to redundancy, fire contro l and malfunction prevention, appropriate treatment for aging degradation or any other appropriate measures. because the evaluation of microcomputer software alone is very difficult, please evaluate the safety of the final products or system manufactured by you. please contact a renesas electronics sales office for details as to environmental matters such as the 11. environmental compatibility of each renesas electronics product. please use renesas electronics products in compliance with all applicable laws an d regulations that regulate the inclusion or use of controlled substances, including without limitation, the eu rohs directive. renesas electronics assumes no liability for damages or losses occurring as a result of your noncompliance with applicable laws and regulations. this document may not be reproduced or duplicated, in any form, in whole or in part, without prior written 12. consent of renesas electronics. please contact a renesas electronics sales office if you have any questions regarding the informati on 13. contained in this document or renesas electronics products, or if you have any other inquiries. renesas electronics as used in this document means renesas electronics corporation and also includes its majority - owned subsidiaries. renesas electronics product(s) means any product developed or manufactured by or for renesas electronics. standard: high quality: specific: note 1 note 2
data flash access library - type t01, european release regional information r01us0079ed0103 4 user manual regional information some information contained in this document may vary from country to country. before using any renesas electronics product in yo ur application, please contact the renesas electronics office in your country to obtain a list of authorized representatives and distributors. they will verify: ? device availability ? ordering information ? product release schedule ? availability of related techn ical literature ? development environment specifications (for example, specifications for third - party tools and components, host computers, power plugs, ac supply voltages, and so forth) ? network requirements in addition, trademarks, registered trademarks, ex port restrictions, and other legal issues may also vary from country to country. visit http://www.renesas.com to get in contact with your regional representatives and distributors.
data flash access library - type t01, european release prefac e r01us0079ed0103 5 user manual preface this manual is intended for users who want to understand the functions of the concerned libraries. this manual presents the software manual for the concerned libraries. additional remark or tip item deserving extra attention binary: xxxx or xxxb decimal: xxxx hexadecimal xxxxh or 0x xxxx representing powers of 2 (address space, memory capacity): k (kilo) 210 = 1024 m (mega): 220 = 1024 2 = 1,048,576 g (giga): 230 = 1024 3 = 1,073,741,824 x, x = dont care block diagrams do not necessarily show the exact software flow but the functional structure. timing diagrams are for functional explanation purposes only, without any relevance to the real hardware implementation. readers purpose note caution numeric notation numeric prefix register diagrams
data flash access library - type t01, european release how to use this document r01us0079ed0103 6 user manual how to use this document (1) purpose and target readers this manual is designed to provide the user with an understanding of the functions and characteristics of the self - programming library. it is intended for users designing application systems incorporating the library. a basic knowledge of embedded systems is necessary in order to use this manual. the manual comprises an overview of the library, api description, usage notes and cautions. particular attention should be paid to the precautionary notes when using the manual. these notes occ ur within the body of the text, at the end of each section, and in the cautions section. the revision history summarizes the locations of revisions and additions. it does not list all revisions. refer to the text of the manual for details. (2) list of abbrevi ations and acronyms abbreviation full form bootloader a piece of software located in the boot cluster handling the reprogramming of the device code flash embedded flash where the application code or constant data is stored. data flash embedded flash where mainly the data of the eeprom emulation are stored. dual operation dual operation is the capability to access flash memory during reprogramming of another flash memory range. dual operation is available between code flash and data fl ash. between different code flash macros dual operation depends on the device implementation. ecc error correction code eel eeprom emulation library eeprom electrically erasable programmable read - only memory eeprom emulation in distinction to a real eeprom the eeprom emulation uses some portion of the flash memory to emulate the eeprom behavior. to gain a similar behavior some side parameters have to be taken in account. fcl code flash library (code flash access layer) fdl d ata flash library (data flash access layer) fhve software protection of flash memory against programming and erasure . not present in all devices. firmware firmware is a piece of software that is located in a hidden area of the device, handling the interfacing to the flash. flash electrically erasable and programmable non - volatile memory. the difference to rom is, that this type of memory can be re - programmed several times. flash block a flash block is the smallest erasable unit of the flash memory.
data flash access library - type t01, european release how to use this document r01us0079ed0103 7 user manual abbreviation full form flash macro a certain number of flash blocks are grouped together in a flash macro. icu intelligent cryptographic unit power save mode device modes to consume less power than during normal operation. in the device documentation also called stan by modes random access memory read only memory
data flash access library - type t01, european r elease r01us0079ed0103 8 user manual table of contents chapter 1 introduction ................................ ................................ ....... 10 chapter 2 architecture ................................ ................................ ....... 11 2.1 layered architecture ................................ ................................ ..................... 11 2.2 pool definitions ................................ ................................ .............................. 12 2.3 architecture related notes ................................ ................................ ............. 12 chapter 3 functional specifications ................................ ................. 14 3.1 supported func tions, commands and flash operations ............................ 14 3.2 request - response oriented dialog ................................ ............................... 15 3.3 background operation ................................ ................................ .................. 16 3.4 flash access protection ................................ ................................ ............... 17 3.5 suspend / resume mech anism ................................ ................................ .... 18 3.6 stand - by and wake - up functionality ................................ ............................ 22 chapter 4 user interface (api) ................................ ........................... 24 4.1 pre - compile configuration ................................ ................................ ............. 24 4.2 run - time configuration ................................ ................................ .................. 24 4.3 data types ................................ ................................ ................................ ....... 26 4.3.1 library specific simple type definitions ................................ ............... 26 4.3.2 r_fdl_descriptor_t ................................ ................................ .................. 26 4.3.3 r_fdl_request_t ................................ ................................ ....................... 27 4.3.4 r_fdl_command_t ................................ ................................ ................... 28 4.3.5 r_fdl_accesstype_t ................................ ................................ ............... 29 4.3.6 r_fdl_status_t ................................ ................................ ......................... 30 4.4 functions ................................ ................................ ................................ ........ 31 4.4.1 initialization ................................ ................................ ............................ 32 4.4.2 flash operations ................................ ................................ ................... 33 4.4.3 operation control ................................ ................................ ................... 37 4.4.4 administration ................................ ................................ ....................... 42 4.5 commands ................................ ................................ ................................ ..... 44 4.5.1 r_fdl_cmd_erase ................................ ................................ ............. 45 4.5.2 r_fdl_cmd_write ................................ ................................ .............. 46 4.5.3 r_fdl_cmd_blankcheck ................................ ................................ 48 4.5.4 r_fdl_cmd_read ................................ ................................ ............... 51 chapter 5 library setup and usage ................................ .................. 55 5.1 obtaining the li brary ................................ ................................ ...................... 55
data flash access library - type t01, european r elease r01us0079ed0103 9 user manual 5.2 file structure ................................ ................................ ................................ .. 55 5.2.1 overview ................................ ................................ ................................ . 55 5.2.2 delivery package directory structure and files ................................ ... 56 5 .3 library resources ................................ ................................ ........................... 58 5.3.1 linker sections ................................ ................................ ...................... 58 5.3.2 stack and data buffer ................................ ................................ ............ 58 5.4 misra compliance ................................ ................................ ........................ 58 5.5 sample application ................................ ................................ ........................ 58 5.6 library configuration ................................ ................................ ..................... 59 5.7 basic reprogramming flow ................................ ................................ .......... 59 5.8 r_fdl_handler calls ................................ ................................ ..................... 61 chapter 6 cautions ................................ ................................ ............. 62
data flash access library - type t01, european release introduction r01us0079ed0103 10 user manual chapter 1 introduction this user manual describes the internal structure, the functionality and the application programming interface (api) of the renesas r h850 data flash access library ( fdl) type 01, designed for RH850 flash devices based on a common flash technology. the libraries are delivered in source code. however it has to be considered carefully to do any changes, as not intended behaviour and programmi ng faults might be the result. the renesas r h850 data flash access library type 01 (from here on referred to as fdl) is provided for the green hills , iar and renesas compiler environments. the library and application programs are distributed using an installer tool allowing selecti ng the appropriate env ironment. the libraries are delivered together with device dependent application programs, showing the implementation of the libraries and the usage of the librar y functions. t he data flash access library, the latest version of this user manual and other device dependent information can be downloaded from the following url: http://www.renesas.eu/update please ensure to always use the latest release of the library in order to take advantage of improvements and bug fixes. this manual is based on the assumption that the device will operate in supervisor mode. for information on other modes, refer to the user's manual for the hardware. note: please read all chapters of this user manual carefully. much attention has been put to proper description of usage conditions and limitations. anyhow, it can never be completely ensured that all incorrect ways of integrating the library into the user application are explicitly forbidden. so, please follow the given sequences and recommendations in this document exactly in order to make full use of the library functionality and features and in order to avoid malfunctions caused by library misuse. flash infrastructure besides the code flash, many devices of the r h850 microcont roller family are equipped with a separate flash area the data flash. this flash area is meant to be used exclusively for data. it cannot be used for instruc tion execution (code fetching). flash granularity the data flash of r h850 device is separated in to blocks of 64 byte. while erase operations can only be performed on complete blocks, data writing can be done on a granularity of one word (4 bytes) . reading from an erased flash word will return random data . the number of available data flash blocks var ies between the different r h850 devices. please refer to the corresponding user's manual for the hardware for detailed information. data flash is divided into flash macro
data flash access library - type t01, european release architecture r01us0079ed0103 11 user manual chapter 2 architecture this chapter introduces the basic software architecture of the fdl and provides the necessary background for application designers to understand and effectively use the library. please read this chapter carefully before moving on to the details of the api description. 2.1 layered architecture this chapter describes the function of all blocks belonging to the eeprom emulation system (ees). even though this manual describes the functional block fdl, a short description of all concerned functional blocks and their relationship can be beneficial for the general understanding. as depicted in the figure above, the software architecture of the eeprom emulation system is built up of several blocks: ? user application : this functional block wil l use functions offered by the fdl and eel . the user shall take care that fdl functions are not used at the same time while eel is operating. please refer to eel documentation for how to stop eel execution in order to safely access fdl functions. ? eeprom em ulation library (eel) : this functional block offers all functions and commands that the user application block can use in or der to handle its eeprom data. ? d ata flash access library (fdl) : the data flash access library is the subject of this manual. it sh ould offer an access interface to any user - defined flash area, the so called fdl - pool (described in next chapter). beside the initialization function, the fdl allows the execution of access - commands like write/blank check as well as suspend - able erase co mmand. figure 1 : symbolic relationship between the ees functional blocks u s e r a p p l i c a t i o n e e l f d l d a t a f l a s h h a r d w a r e c o d e f l a s h
data flash access library - type t01, european release architecture r01us0079ed0103 12 user manual ? data flash hardwar e: this functional block represents the flash programming hardware controlled by the fdl. 2.2 pool definitions the fdl pool defines the flash blocks, the user application and a potential eeprom emulation (eel) may use for fdl flash access. the limits of the fdl pool are taken into consideration by any of the fdl flash access commands. the user can define the size of the fdl po ol freely at project run - time during library initialization. the fdl pool provides the space for the eel pool which is allocated by the eel inside the fdl pool . the eel pool provides the flash space for the eel to store the emulation data and management in formation. all fdl pool space not allocated by the eel pool is freely usable by the user application, so is called the user pool . 2.3 architecture related notes ? all data flash related operations are ex ecuted by the fdl. thus, the application cannot access (erase, write ...) the data flash directly. an exception is reading the flash contents. as the flash is mapped to the cpu address space, it can be directly read by the cpu. the fdl provides an addition al read operation that will take care of possible eccs (error correction code) errors to allow error polling. ? the fdl allows accessing the data flash only. figure 2 : pools overview u s e r p o o l e e l p o o l u s e r p o o l d a t a f l a s h / f d l p o o l f d l p o o l
data flash access library - type t01, european release architecture r01us0079ed0103 13 user manual ? parallel flash operations (except read by the cpu) on data flash and code flash are not possible due to shared reso urces between the flash macros.
data flash access library - type t01, european release functio nal specifications r01us0079ed0103 14 user manual chapter 3 functional specifications 3.1 supported functions, commands and flash operations for a better understanding of the flows and mechanisms required for an fdl usage, the basic functions of the fdl are introduced in the following. the api of the fdl is thereby, on the one hand based on functions used to manage the operation of the library itself, on the other hand it offers so - called commands to access and control the content of the fdl pool. the following table list s up all functions, the library will support. please refer to the chapter 4.4 functions for detailed descriptions. table 1 : fdl function function description r_fdl_init initialize the library and flash hardware r_fdl_execute in itiate a flash operation r_fdl_handler control an initiated flash operation and forward the status. r_fdl_suspendrequest request suspending an on - going flash operation r_fdl_resumerequest resume a suspended flash operation r_fdl_standby suspend an on - going flash operation from an asynchronous context r_fdl_wakeup wake - up the fdl from stand - by state r_fdl_getversionstring return a pointer to the library version string commands are used to manage the fdl pool . commands are initiated via r_fdl_execute and the further progress is controlled by regular execution of r_fdl_handler . the following commands can be used to execute the following flash operations: table 2 : fdl commands and operation s command initiated flash operation description r_fdl_cmd_erase flash erase erase one or more flash blocks r_fdl_cmd_write flash write write one or more flash words r_fdl_cmd_blankcheck flash blank check blank check one or more flash words. return the fail address in case some flash word is not blank r_fdl_cmd_read flash data read read one or more flash words to a buffer. return a possible ecc (error correction code) error to the application together with the address of the error the following picture shows the basic flow of flash operations at the example of erasing 2 flash blocks. while the flash hardware can only erase or write one unit (erase 1 block, write 1 word), the fdl will manage handling multiple units. blank check is executed on word basis but internally it is spli t in multiple units at each multiple of 0x4000 bytes boundary .
data flash access library - type t01, european release functional specifications r01us0079ed0103 15 user manual 3.2 request - r esponse o riented d ialog the fdl utilizes request - response architecture in order to initiate the commands. this means any "requester" (any tasks in the user application) has to fill a request structure and pass it by reference to the data flash access library using r_fdl_execute function. the fdl interprets the content of the request variable, checks its plausibility and initiates the execution. the feedback is reflected immediately to the requester via the status member ( status_enu ) of the same request structure . the completion of an accepted request/command is done by calling r_fdl_handler periodically as long as the request remains "busy". figure 3 : flash erase sequence e r a s e 1 b l o c k r _ f d l _ e x e c u t e ( e r a s e 2 b l o c k s ) s t a r t e r a s e b l k 1 r _ f d l _ b u s y r _ f d l _ h a n d l e r r _ f d l _ b u s y c h e c k ( b u s y ) r _ f d l _ h a n d l e r r _ f d l _ b u s y c h e c k ( b u s y ) r _ f d l _ h a n d l e r r _ f d l _ b u s y c h e c k ( r e a d y ) s t a r t e r a s e b l k 2 e r a s e n e x t b l o c k r _ f d l _ h a n d l e r r _ f d l _ b u s y c h e c k ( b u s y ) r _ f d l _ h a n d l e r r _ f d l _ b u s y c h e c k ( b u s y ) r _ f d l _ h a n d l e r r _ f d l _ o k c h e c k ( r e a d y ) . . . . . . u s e r a p p l i c a t i o n f d l d a t a f l a s h p r o g r a m m i n g h a r d w a r e
data flash access library - type t01, european release functional specifications r01us0079ed0103 16 user manual d etails on the request variable structure and its members are given later in section 4.3. 3 r_fdl_request_t . please also note that not all structure members are required for all commands. the individual command descriptions in section 4.5 commands provide the corresponding det ailed information. 3.3 background operation the flash technology provided by renesas enables the application to write/erase the data flash in parallel to the cpu execution. in order to satisfy the operation in concurrent or distributed systems, the command ex ecution is divided int o two steps: 1. initiation of the command execution using r_fdl_execute 2. processing of the requested comman d state by using r_fdl_handler this approach comes with one important advantage: command processing can be done centrally at one place in the target system (normally the idle - loop or the scheduler loop), while the status of the requests can be polled locall y within the requesting tasks. please note that r_fdl_execute only initiates the command execution and returns immediate ly with the request - status "busy" after execution of the first internal state (or an error in case the request cannot be accepted). the device flash hardware is responsible for executing the operation in the background. the device hardware operation might be divided into multiple operations, each performed on a separate occasion, depending on the number of blocks and data items. the first operation is conducted by calling t he r_fdl_execute function. the second and subsequent operations are triggered by call ing the r_fdl_handler function. thus, there is a need to call the r_fdl_handler function multiple times. processing is suspended from the time each separate operation is completed until the next one is triggered. therefore, as the time interval between r_f dl_handler functions call increases, so does the overall processing time. an exception to this background operation is r_fdl_cmd_read command that is executed synchronously during r_fdl_execute function. figure 4 : usage of the request structure a p p l i c a t i o n b u f a d d r _ u 3 2 i d x _ u 3 2 c n t _ u 1 6 a c c e s s t y p e _ e n u m y r e q u e s t s t a t u s _ e n u f d l c o m m a n d _ e n u
data flash access library - type t01, european release functional specifications r01us0079ed0103 17 user manual 3.4 flash access protection the fdl flash access protection shall protect flash accesses to unintended addresses. the protection distinguishes eel - pool flash blocks from user - pool blocks (refer to chapter 2.2 pool definitions for more information). an access as user application will be allowed to all configured flash blocks outside the eel - pool, while an access from eel will be allowed to the eel - pool only. generally, on any data flash operation initiation, the access type mu st be defined in the operation request structure variable. setting this variable enables the access either to the eel - pool or to the data flash blocks outside the eel - pool (user - pool). if the variable is not initialized appropriately or if the wrong pool s hall be accessed, a protection error is returned. figure 5 : background o peration u s e r a p p l i c a t i o n f d l d a t a f l a s h p r o g r a m m i n g h a r d w a r e r _ f d l _ e x e c u t e ( c o m m a n d * ) s t a r t f l a s h o p e r a t i o n r _ f d l _ b u s y r _ f d l _ h a n d l e r ( ) r _ f d l _ b u s y r _ f d l _ h a n d l e r ( ) r _ f d l _ b u s y s t a t u s c h e c k o p e r a t i o n i s o n g o i n g s t a t u s c h e c k o p e r a t i o n i s f i n i s h e d s t a r t f l a s h o p e r a t i o n o p e r a t i o n s t a r t e d s t a t u s c h e c k o p e r a t i o n i s f i n i s h e d r _ f d l _ h a n d l e r ( ) r _ f d l _ o k o t h e r o p e r a t i o n s m a y f o l l o w l i b r a r y i s b u s y w i t h a f l a s h o p e r a t i o n * p o s s i b l e a s y n c h r o n o u s c o m m a n d s : ? r _ f d l _ c m d _ e r a s e ? r _ f d l _ c m d _ w r i t e ? r _ f d l _ c m d _ b l a n k c h e c k
data flash access library - type t01, european release functional specifications r01us0079ed0103 18 user manual 3.5 suspend / resume mechanism some data flash operations can last a long time especially multiple erase and write . the user application cannot always wait for the operation end because other operations have higher priority . so, from user point of view current operation is suspend - able and can be resumed after finishing the other flash accesses. from software point o f view an on - going operation always ends in suspended state unless the resume is requested beforehand. in case the flash hardware has already finished an operation but its end result has not already been processed by the library, the library returns the su spended status. the final operation result is returned after successful resume request. the fdl contains special functions to suspend and resume an ongoing operation. please refer to chapter 4.4.3.1 r_fdl_suspendrequest . examples of erase or write suspend - resume flow: figure 6 : flash access rights u s e r p o o l e e l p o o l u s e r p o o l d a t a f l a s h / f d l p o o l u s e r a p p l i c a t i o n e e l
data flash access library - type t01, european release functional specifications r01us0079ed0103 19 user manual figure 7 : erase/write suspend resume flow e r a s e 1 b l o c k o r w r i t e 1 w o r d r _ f d l _ e x e c u t e ( e r a s e / w r i t e ) s t a r t u n i t 1 r _ f d l _ b u s y r _ f d l _ h a n d l e r r _ f d l _ b u s y c h e c k ( b u s y ) . . . u s e r a p p l i c a t i o n f d l d a t a f l a s h p r o g r a m m i n g h a r d w a r e e r a s e o r w r i t e n e x t u n i t ( r e s u m e d ) s u s p e n d e d i d l e r _ f d l _ s u s p e n d r e q u e s t r _ f d l _ o k r _ f d l _ h a n d l e r r _ f d l _ b u s y s u s p e n d r _ f d l _ h a n d l e r r _ f d l _ s u s p e n d e d c h e c k ( s u s p e n d e d ) r _ f d l _ r e s u m e r e q u e s t r _ f d l _ o k r _ f d l _ h a n d l e r r _ f d l _ b u s y r e s u m e r _ f d l _ h a n d l e r r _ f d l _ b u s y c h e c k ( b u s y ) r _ f d l _ h a n d l e r r _ f d l _ o k c h e c k ( r e a d y ) . . . . . .
data flash access library - type t01, european release functional specifications r01us0079ed0103 20 user manual blankcheck operation will not be interrupted by a suspend request unless the operation reaches a flash macro boundary ( any multiple of 0x4000 bytes) or it will be finished : figure 8 : erase/write suspend + immediate resume e r a s e 1 b l o c k o r w r i t e 1 w o r d r _ f d l _ e x e c u t e ( e r a s e o r w r i t e ) s t a r t u n i t 1 r _ f d l _ b u s y r _ f d l _ h a n d l e r r _ f d l _ b u s y c h e c k ( b u s y ) . . . u s e r a p p l i c a t i o n f d l d a t a f l a s h p r o g r a m m i n g h a r d w a r e i d l e r _ f d l _ s u s p e n d r e q u e s t r _ f d l _ o k r _ f d l _ r e s u m e r e q u e s t r _ f d l _ o k r _ f d l _ h a n d l e r r _ f d l _ b u s y c h e c k ( b u s y ) r _ f d l _ h a n d l e r r _ f d l _ o k c h e c k ( r e a d y ) . . .
data flash access library - type t01, european release functional specifications r01us0079ed0103 21 user manual note s : when erase processing is suspended and resumed, this is not considered as an additional erase with respect to the specif ied flash erase endurance. the suspend / resume mechanism cannot be nested. therefore, the following sequence is not allowed: erase flash ? suspend ? start another e rase f lash ? suspend . figure 9 : suspend/resume a blankcheck operation b l a n k c h e c k 0 x 3 0 0 0 t o 0 x 3 f f f r _ f d l _ e x e c u t e ( b l a n k c h e c k 0 x 3 0 0 0 t o 0 x 4 f f f ) s t a r t b l a n k c h e c k r _ f d l _ b u s y r _ f d l _ h a n d l e r r _ f d l _ b u s y c h e c k ( b u s y ) . . . u s e r a p p l i c a t i o n f d l d a t a f l a s h p r o g r a m m i n g h a r d w a r e r _ f d l _ s u s p e n d r e q u e s t r _ f d l _ o k r _ f d l _ r e s u m e r e q u e s t r _ f d l _ o k r _ f d l _ h a n d l e r r _ f d l _ b u s y c h e c k ( b u s y ) r _ f d l _ h a n d l e r r _ f d l _ s u s p e n d e d c h e c k ( r e a d y ) . . . r _ f d l _ h a n d l e r r _ f d l _ o k / _ e r r _ b l a n k c h e c k b l a n k c h e c k 0 x 4 0 0 0 t o 0 x 4 f f f s t a r t b l a n k c h e c k r _ f d l _ h a n d l e r r _ f d l _ b u s y c h e c k ( b u s y ) . . . i d l e r _ f d l _ s u s p e n d r e q u e s t r _ f d l _ o k r _ f d l _ r e s u m e r e q u e s t r _ f d l _ o k r _ f d l _ h a n d l e r r _ f d l _ b u s y c h e c k ( b u s y ) . . . r _ f d l _ h a n d l e r r _ f d l _ o k / _ e r r _ b l a n k c h e c k s u s p e n d e d r _ f d l _ h a n d l e r r _ f d l _ s u s p e n d e d c h e c k ( r e a d y ) s u s p e n d e d
data flash access library - type t01, european release functional specifications r01us0079ed0103 22 user manual 3.6 stand - by and wake - up functionality entering a device power save (stand - by) mode is not allowed, when a data flash operation is on - going. due to that, especially data flash erase operation can delay entering a power save mode significantly. in order to allo w fast entering of such mode, the functions r_fdl_standby and r_fdl_wakeup have been introduced. the main functionality of the functions is to suspend a possibly on - going data flash erase or write operation ( r_fdl_standby ) and resume it after waking up fro m power save mode ( r_fdl_wakeup ). once started, stand - by processing must always end in stand - by status. calling the r_fdl_standby does not necessarily immediately suspend any data flash operation, as suspend might be delayed by the device internal hardwar e or might not be supported at all (only erase and write are suspend - able). in this case, the r_fdl_standby function must be called repeatedly until the stand - by status is reached. blank check and read data flash operations are suspendable from software po int of view, but the library will wait for the operation to be finished by hardware while suspend is processed and the result will be presented after resuming. this wait however is not that important because blank check and read operations are much faster than erase or write. in case the fdl is in an idle state (no on - going data flash operations), by calling the r_fdl_standby the fdl will immediately enter the stand - by state. by calling the r_fdl_wakeup , the fdl will return to previous state (in this case t he idle state). the following pictures describe the library behaviour in case a stand - by request is issued during fdl operation: figure 10 : stand - by processing on a data flash erase operation e r a s e f i r s t b l o c k r _ f d l _ e x e c u t e ( e r a s e 2 b l o c k s ) s t a r t e r a s e b l o c k r _ f d l _ b u s y r _ f d l _ h a n d l e r r _ f d l _ b u s y c h e c k ( b u s y ) u s e r a p p l i c a t i o n f d l d a t a f l a s h p r o g r a m m i n g h a r d w a r e e r a s e b l o c k 2 s t a n d b y s t a t e i d l e r _ f d l _ s t a n d b y r _ f d l _ o k s u s p e n d r _ f d l _ w a k e u p r _ f d l _ o k s t a r t e r a s i n g i n t e r r u p t e d b l o c k r _ f d l _ h a n d l e r r _ f d l _ b u s y c h e c k ( b u s y ) r _ f d l _ h a n d l e r r _ f d l _ o k c h e c k ( r e a d y ) e r a s e s e c o n d b l o c k r _ f d l _ h a n d l e r s t a r t e r a s e b l o c k r _ f d l _ b u s y r _ f d l _ h a n d l e r r _ f d l _ b u s y c h e c k ( b u s y ) e r a s e s e c o n d b l o c k i n t e r r u p t e d
data flash access library - type t01, european release functional sp ecifications r01us0079ed0103 23 user manual figure 11 : stand - by processing on a data flash write operation w r i t e f i r s t w o r d r _ f d l _ e x e c u t e ( w r i t e 3 w o r d s ) s t a r t w r i t e b y t e r _ f d l _ b u s y r _ f d l _ h a n d l e r r _ f d l _ b u s y c h e c k ( b u s y ) u s e r a p p l i c a t i o n f d l w r i t e t h i r d w o r d s t a n d b y s t a t e i d l e r _ f d l _ s t a n d b y r _ f d l _ b u s y s u s p e n d r _ f d l _ w a k e u p r _ f d l _ o k c o n t i n u e t h e w r i t e o p e r a t i o n r _ f d l _ h a n d l e r r _ f d l _ b u s y c h e c k ( b u s y ) r _ f d l _ h a n d l e r r _ f d l _ o k c h e c k ( r e a d y ) w r i t e s e c o n d w o r d r _ f d l _ h a n d l e r s t a r t w r i t e b y t e r _ f d l _ b u s y d a t a f l a s h p r o g r a m m i n g h a r d w a r e r _ f d l _ o k s u s p e n d r _ f d l _ s t a n d b y
data flash access library - type t01, european release user interface (api) r01us0079ed0103 24 user manual chapter 4 user interface (api) this chapter provides the formal description of the application programming interface of the flash data library type t01 (fdl). it is strongly advised to read and understand the previous chapters presenting the concepts and structures of the library before continuing with the api details. 4.1 pre - compile configuration the pre - compile configuration has a direct impact on the object file generated by the compil er. hence it is used for conditional compilation (e.g. solve device dependencies of the code). the configuration is done in the module fdl_cfg.h . the user has to configure all parameters and attributes by adapting the related constant definitions in that h eader - file. the following configuration options are available: 1. critical section one configuration element is the critical section handling of the library. the function r_fdl_init needs to activate the device internal special memory for a short time in orde r to have access to certain data. this results in disabling the code flash. during that time, code from code flash cannot be executed as well as data cannot be read. the library provides the possibility to execute call - back routines in order for the user to handle the implications of disabling the code flash (for the impact on the application, please refer to chapter 6 cautions ). the call - back routines are executed at the begin and e nd of the critical section. the defines to set the call back routines are described in the following: fdl_critical_section_begin : possibility to execute a call back routine at critical section start (e.g. disable int errupts and exceptions) fdl_critical_section_end : possibility to execute a call back routine at critical section end (e.g. enable interrupts and exceptions) i mplementation in the sample application : #define fdl_critical_section_begin fdl_user_criticalsetio nbegin(); #define fdl_critical_section_end fdl_user_criticalsetionend(); device family 2. the macro fdl_cfg_e1x_p1x_platform must be defined for e1x and p1x and must be left undefined for f1x and r1x devices. 4.2 run - time configuration the fdl configuration can be changed dynamically at runtime. it contains important fdl related information (e.g. cpu frequency, number of blocks used by library , authentication code ) and eel information (e.g. eel pool size and eel starting block number). the run - time configurat ion is stored in a descriptor structure (see r_fdl_descriptor_t ), which is declared in r_fdl_types.h , but defined in the user application and passed to the library by the function r_fdl_init . the file fdl_descriptor.c shall show an example of the descripto r structure definition and filling, while the fdl_descriptor.h shall show an example of the definitions required to fill in the structure. in fact, the file fdl_descriptor.h might be modified according to the user applications needs and might be added to the user application project together with the fdl_descriptor.c . the descriptor files (.c and .h) are part of the library installation package.
data flash access library - type t01, european release user interface (api) r01us0079ed0103 25 user manual the following settings should be configured by user: 1. authentication_id: a 16 b yte access id code . the id code i s used to secure access to: 1. on chip debug unit 2. serial programming 3. self - programming only on older f1x devices. newer devices will simply ignore a wrong id code so self - programmi ng feature is always available. on older devices where id code is still checked, a wrong code will not result in a failed initialization but fdl commands will fail to operate with a r_fdl_err_protection error status. 2. cpu_frequency_mhz: this defines the internal cpu frequency in mhz unit, rounded up to the nearest integer , e.g. for 24.3 mhz set cpu_frequency_mhz to 25 . please check the device manual for limit values 3. fdl_pool_size: it defines the number of blocks to be accessed by the fdl for user access and eel access. usually it is set to the total number of blocks physic ally available on the device. for example, if the device is equipped with 32 kb of data flash and the block size is 64 bytes, then fdl_pool_size can be any value up to 512 4. eel_pool_start: it defines the starting block of the eel - pool. if fdl is used withou t eel on to p, the value should be set to 0 5. eel_pool_size: it defines the number of blocks used for the eel - pool. if fdl is used without eel on to p, the value should be set to 0 fdl block size is always equal to the physical block size of data flash. e xample of descriptor when fdl is used alone : /* default access code */ #define authentication_id { 0xffffffff, \ 0xffffffff, \ 0xffffffff, \ 0xfffff fff } #define cpu_frequency_mhz ( 80 ) /* fdl pool will use 512 blocks * 64 bytes = 32kb, no eel pool */ #define fdl_pool_size ( 512 ) #define eel_pool_start ( 0 ) #define eel_pool_size ( 0 ) example of descriptor when eel is used : /* default access code */ #define authentication_id { 0xffffffff, \ 0xffffffff, \ 0xffffffff, \ 0xffffffff } #define cpu_frequency_mhz ( 80 ) /* fdl pool will use 32kb, eel pool occupies fist 16 kb */ #define fdl_pool_size ( 512 ) #define eel_pool_start ( 0 ) #define eel_pool_size ( 256 ) eel may be configured to use virtual blocks. a virtual block size is an integer m ultiple of physical block size and it is aligned to physical blocks. please consult eel documentation for details. example of descriptor when eel is used with virtual block size 32 times the size of physical bloc k size :
data flash access library - type t01, european release user interface (api) r01us0079ed0103 26 user manual /* default access code */ #define authentication_id { 0xffffffff, \ 0xffffffff, \ 0xffffffff, \ 0xffffffff } #define cpu_frequency_mhz ( 80 ) #define fdl_pool_size ( 512 ) /* fdl pool will use 32kb, from wich eel pool occupies area: start: 1 * 32 * 64 = 2048 till end: 6 * 32 * 64 + 2048 = 14335 */ #define eel_virtualblocksize ( 32u ) #define eel_pool_start ( 1u * eel_virtualblocksize ) #define eel_pool_size ( 6u * eel_virtualblocksize ) 4.3 data types this section describes all data definitions used and offered by the fdl. in order to reduce the probability of type mismatches in the user application, please make strict usage of the provided types. 4.3.1 library specific simple type definitions type definition: typedef signed char int8_t; typedef unsigned char uint8_t; typedef signed short int16_t; typedef unsigned short uint16_t; typedef signed long int32_t; typedef unsigned long uint32_t; typedef unsigned char rbool; description: these simple types are used throughout the complete library api. all library specific simple type definitions can be found in file r_typedefs.h , which is part of the library installation package. 4.3.2 r_fdl_ descriptor_t type definition: typedef struct r_fdl_descriptor_t { uint32_t id_au32[4]; uint16_t cpufrequencymhz_u16; uint16_t fdlpoolsize_u16; uint16_t eelpoolstart_u16; uint16_t eelpoolsize_u16; } r_fdl_descriptor_t;
data flash access library - type t01, european release user interface (api) r01us0079ed0103 27 user manual description: this type is the run - time configuration (see chapter 4.2 ). a member / value: member / value description id_au32[4] authentication id array code cpufrequencymhz_u16 cpu frequency in mhz fdlpoolsize_u16 fdl pool size in number of blocks eelpoolstart_u16 number of first block of the eel pool eelpoolsize_u16 last block of the eel pool 4.3.3 r_fdl_request_t type definition: typedef volatile struct r_fdl_request_t { r_fdl_command_t command_enu; uint32_t bufaddr_u32; uint32_t idx_u32; uint16_t cnt_u16; r_fdl_accesstype_t accesstype_enu; r_fdl_status_t status_enu; } r_fdl_request_t; description: this s tructure is the central type for the request - response - oriented dialog for the command execution (see section 3.2 request - r esponse o riented d ialog ). not every element of this structure is required for each command. however, all members of the request variable must be initialized once before usage. please refer to section 4.5 commands for a more detailed description of the structure elements command - specific usage. for simplification, idx_u32 structure member is a virtual address that starts at 0x0 and not at the address at which data flash is mentioned in the hardware user manual.
data flash access library - type t01, european release user interface (api) r01us0079ed0103 28 user manual member / value: member / value description command_enu user command to execute : ? ? ? ? ? ? ? ? ? 4.3.4 r_fdl_command_t type definition: typedef enum r_fdl_command_t { r_fdl_cmd_erase, r_fdl_cmd_write, r_fdl_cmd_blankcheck, r_fdl_cmd_read } r_fdl_command_t; description: user command to execute. this type is used within the structure r_fdl_request_t (see section 4.3.3 " r_fdl_request_t " ) in order to specify which command shall be executed via the function r_fdl_execute . a detailed description of each command can be found in section 4.5 commands .
data flash access library - type t01, european release user interface (api) r01us0079ed0103 29 user manual member / value: member / value description r_fdl_cmd_erase erase data flash block (s) r_fdl_cmd_write write data flash word(s) r_fdl_cmd_blankcheck blank check certain data flash area r_fdl_cmd_read read from data flash and return data and possible ecc errors 4.3.5 r_fdl_accesstype_t type definition: typedef enum r_fdl_access_type_t { r_fdl_access_none, r_fdl_access_user, r_fdl_access_eel } r_fdl_accesstype_t; description: in order to initiate a data flash operation, the access type to the data flash must be set depending on the configured pool tha t will be accessed . the pool ranges are defined in the fdl descriptor, passed to the r_fdl_init function (please check figure 6: flash access rights ). after each operation the access right is reset to r_fdl_access_none to prevent accidental access. member / value: member / value description r_fdl_access_none fdl internal value. not used by the application r_fdl_access_user application wants to execute an fdl operation in the user - pool data flash area r_fdl_access_eel application wants to execute an fdl operation in the eel - pool data flash area
data flash access library - type t01, european release user interface (api) r01us0079ed0103 30 user manual 4.3.6 r_fdl_status_t type definition: typedef enum r_fdl_status_t { r_fdl_ok, r_fdl_busy, r_fdl_suspended, r_fdl_err_configuration, r_fdl_err_parameter, r_fdl_err_protection, r_fdl_err_rejected, r_fdl_err_write, r_fdl_err_erase, r_fdl_err_blankcheck, r_fdl_err_command, r_fdl_err_ecc_sed, r_fdl_err_ecc_ded, r_fdl_err_internal } r_fdl_status_t; des cription: this enumeration type defines all possible status and error - codes that can be generated by the fdl. some error codes are command specific and are described in detail in section 4.5 commands .
data flash access library - type t01, european release user interface (api) r01us0079ed0103 31 user manual member / value: member / value description r_fdl_ok fdl o peration s uccessfully finished r_fdl_busy fdl o peration is still ongoing r_fdl_suspended data flash operation is suspended r_fdl_err_configuration the fdl configuration (descriptor) was wrong r_fdl_err_parameter an error was found in the given parameter(s) r_fdl_err_protection fdl operation stopped due to hardware error, wrong access rights or wrong conditions r_fdl_err_rejected a flow error occurred (e.g. library not initialized, other operation on - going) r_fdl_err_write data flash write error r_fdl_err_erase data flash erase error r_fdl_err_blankcheck the blank check command was stopped because the specified area is not blank r_fdl_err_command unknown command r_fdl_err_ecc_sed single bit error det ected by ecc r_fdl_err_ecc_ded double bit error detected by ecc r_fdl_err_internal the current fdl command stopped due to an library internal error (e.g. hardware errors that should never occur or library errors which were not expected and might result from library data manipulation by the application) 4.4 functions the api functions, grouped by their role in the interface: initialization: ? r_fdl_ init flash operations: ? r_fdl_execute ? r_fdl_handler operation control: ? r_fdl_suspendrequest ? r_fdl_resumerequest ? r_fdl_standby ? r_fdl_wakeup
data flash access library - type t01, european release user interface (api) r01us0079ed0103 32 user manual administration: ? r_fdl_getversionstring the following sub - chapters describe the flash operations that can be initiated and controlled by the library. the operations are initiated by a library function r_fdl_execute and later on controlled by the library function r_fdl_han dler . all fdl interface functions are prototyped in the header file r_fdl.h . 4.4.1 initialization 4.4.1.1 r_fdl_ init outline: initialization of the data flash access library. interface: c interface r_fdl_status_t r_fdl_init (const r_fdl_descriptor_t * descriptor_pstr); arguments: parameters argument type access description descriptor_pstr r_fdl_descriptor_t * r fdl configuration descriptor (see section 4.3.2 r_fdl_request_t ) return value type description r_fdl_status_t ? r_fdl_ok operation finished successfully. ? r_fdl_err_configuration wrong parameters have been passed to the fdl: ? descriptor address is null ? fdl - pool is zero ? eel - pool ends beyond fdl - pool edge ? specified cpu clock is outside limits for this device ? r_fdl_err_internal initialization failed due to various factors (insufficient stack space, unknown hardware or software issues) pre - conditions: interrupt execution shall be disabled for a brief time during execution of this function. this must either be done in advance by the user, or the user must properly configure provided callback macro functions in fdl_cfg.h (see description and example below ). post - conditions: none
data flash access library - type t01, european release user interface (api) r01us0079ed0103 33 user manual description: this function is executed before any execution of fdl flash operation. function checks the input parameters and initialize s the hardware and software. note: this function will temporarily disable code flash. please refer to chapter 6 cautions for limitations that must be considered . example: const r_fdl_descriptor_t sampleapp _fdlconfig_enu = { authentication_id, cpu_frequency_mhz, fdl_pool_size, eel_pool_start, eel_pool_size }; r_fdl_status_t ret; ret = r_fdl_init (& sampleapp _fdlconfig_enu); if (ret != r_fdl_ok) { /* error handler */ } example: for setting the protected section with callbacks provided in the sample application #define fdl_critical_section_begin fdl_user_criticalsetionbegin(); #define fdl_critical_section_end fdl_user_criticalsetionend(); 4.4.2 flash operations 4.4.2.1 r_fdl_execute outline: initiate a data flash operation. interface: c interface void r_fdl_execute (r_fdl_request_t * request_pstr); arguments: parameters argument type access description request_pstr r_fdl_request_t * rw this argument points to a request structure defining the command , command parameters and also the execution results. a more detailed description of request structure can be found in section 4.3.3 r_fdl_request_t .
data flash access library - type t01, european release user interface (api) r01us0079ed0103 34 user manual return value type description none pre - conditions: r_fdl_init must have been executed successfully. post - conditions: call r_fdl_handler until the flash operation is finished. this is reported by the request structure status return value (value changes from r_fdl_busy to a different value). the user application must not modify members of the request structure while the command is in operat ion. description: the execute function initiates all flash modification operations. the operation type and operation parameters are passed to the fdl by a request structure, the status and the result of the operation are returned to the user application also by the same structure. the required parameters as well as the possible return values depend on the operation to be started. this function only starts a hardware operation according to the command to be executed. the command processing must be control led and stepped forward by the handler function r_fdl_handler . possible commands, parameters and return values are described into chapter 4.5 commands . example: erase blocks 0 to 3. r_fdl_request_t myrequest; myrequest.comma nd_enu = r_fdl_cmd_erase; myrequest.idx_u32 = 0; m yrequest.cnt_u16 = 4; myrequest.accesstype_enu = r_fdl_ access_user; r_fdl_execute (&myrequest); while (myreq uest.status_enu == r_fdl_busy) { r_fdl_handler (); } if (my request. status_enu != r_fdl_ok) { /* error handler */ } example: write 8 bytes starting from addresses 0x10 . r_fdl_request_t myrequest; uint 32 _t data[] = { 0x11223344, 0x556677 88 }; myrequest.comma nd_enu = r_fdl_cmd_write; myreq uest.idx_u32 = 0x10; m yrequest.cnt_u16 = 2; myrequest. bufaddr_u32 = (uint32_t)&data[0]; myrequest.accesst ype_enu = r_fdl_access_user; r_fdl_execute (&myrequest); while (myreq uest.status_enu == r_fdl_busy)
data flash access library - type t01, european release user interface (api) r01us0079ed0103 35 user manual { r_fdl_handler (); } if (myr equest.status_enu != r_fdl_ok) { /* error handler */ } example: blank check addresses from 0x10 to 0x17. r_fdl_request_t myrequest; myrequest.command_enu = r_fdl_cmd_blankcheck; myrequest.idx_u32 = 0x10; myrequest.cnt_u16 = 2; myrequest.accesstype_enu = r_fdl_access_user; r_fdl_execute(&myrequest); while (myrequest.status_enu == r_fdl_busy) { r_fdl_handler(); } if (myrequest.status_enu != r_fdl_ok) { /* error handler */ } example: read two words starting from address 0x10 . r_fdl_request_t myrequest; uint32_t data[2]; myrequest.command_enu = r_fdl_cmd_read; myrequest.idx_u32 = 0x10; myrequest.cnt_u16 = 2; myrequest.bufaddr_u32 = (uint32_t)&data[0]; myrequest.accesstype_enu = r_fdl_access_user; r_fdl_execute(&myrequest); if (myrequest.status_enu != r_fdl_ok) { /* error handler */ }
data flash access library - type t01, european release user interface (api) r01us0079ed0103 36 user manual 4.4.2.2 r_fdl_handler outline: this function needs to be called repeatedly in order to drive pending commands and observe their progress. interface: c interface void r_fdl_handler (void); arguments: parameters argument type access description none return value type description none pre - conditions: r_fdl_init and r_fdl_execute must have been executed successfully. post - conditions: the status of a pending fdl command may be updated, i.e. the status_enu member of the corresponding request structure is written. description: the function needs to be called regularly in order to drive pending commands and observe their progress. thereby, the command execution is performed state by state. when a command execution is finished, the request status variable (structural element status_enu of r_fdl_request_t ) is updated with the status/error code of the corresponding command execution. note: when no command is being processed, r_fdl_handler consumes few cpu cycles. example: while (true) { r_fdl_handler(); user_task_a(); user_task_b(); user_task_c(); user_task_d(); }
data flash access library - type t01, european release user interface (api) r01us0079ed0103 37 user manual 4.4.3 operation control 4.4.3.1 r_fdl_suspendrequest outline: this function requests suspending a flash operation in order to be able to do other flash operations. interface: c interface r_fdl_status_t r_fdl_suspendrequest (void); arguments: parameters argument type access description none return value type description r_fdl_status_t ? r_fdl_ok operation finished successfully ? r_fdl_ err_ rejected wrong library handling flow : ? no operation is ongoing ? fdl is already in suspended state pre - conditions: a flash o peration must have been started and not yet finished (request structure status value is r_fdl_busy ). the fdl must not be processing another suspend request. post - conditions: call r_fdl_handler until the library is suspended (status r_fdl_suspended ) if the function returned successfully, no further error check of the suspend procedure is necessary, as a potential error is saved and restored on r_fdl_resumerequest . the request structure used before suspend shall not be modified by the command(s) issued during suspended state. description: this function requests suspending a flash operation in order to be able to do other flash operations. example: r_fdl_status_t srres_enu; r_fdl_request_t myreq_str_str; uint32_t i; /* start erase operatio n */ myreq_str_str.command_enu = r_fdl_cmd_erase; myreq_str_str.idx_u32 = 0; myreq_str_str.cnt_u16 = 4; myreq_str_str.accesstype_enu = r_fdl_access_user; r_fdl_execute (&myreq_str_str);
data flash access library - type t01, european release user interface (api) r01us0079ed0103 38 user manual /* now call the handler some times */ i = 0; while ( (myreq_str_str.status_enu == r_fdl_busy) && (i < 10) ) { r_fdl_handler (); i++; } /* suspend request and wait until suspended */ srres_enu = r_fdl_suspendrequest (); if (r_fdl_ok != srres_enu) { /* error handler */ while (1) ; } while (r_fdl_suspended != myreq_str_str.status_enu) { r_fdl_handler (); } /* now the fdl is suspended and we can handle other operations or read the data flash ... */ /* erase resume */ srres_enu = r_fdl_resumerequest(); if (r_fdl_ok != srres_enu) { /* error handler */ } /* finish the erase */ while (myreq_str_str.status_enu == r_fdl_suspended) { r_fdl_handler(); } while (myreq_str_str.status_enu == r_fdl_busy) { r_fdl_handler(); } if (r_fdl_ok != myreq_str_str.status_en u) { /* error handler */ } 4.4.3.2 r_fdl_resumerequest outline: this function requests to resume the fdl operation after suspending. interface: c interface r_fdl_status_t r_fdl_resumerequest (void);
data flash access library - type t01, european release user interface (api) r01us0079ed0103 39 user manual arguments: parameters argument type access description none return value type description r_fdl_status_t ? r_fdl_ok operation finished successfully ? r_fdl_ err_ rejected wrong library handling flow : fdl is not in suspended or suspend pending state pre - conditions: the library must be in suspended state. post - conditions: call r_fdl_handler until the library operation is resumed . description: this function requests to resume the fdl operation after suspending. the resume is just requested by this function. resume handling is done by the r_fdl_handler function. example: see r_fdl_suspendrequest . 4.4.3.3 r_fdl_standby outline: this function suspends an ongoing flash operation . interface: c interface r_fdl_status_t r_fdl_standby (void); arguments: parameters argument type access description none
data flash access library - type t01, european release user interface (api) r01us0079ed0103 40 user manual return value type description r_fdl_status_t ? ? ? ? ? pre - conditions: r_fdl_init must have been executed successfully. fdl is not in stand - by mode. post - conditions: repeat the execution of the r_fdl_standby function until the state indicated by the function changes from r_fdl_busy . do not execute functions r_fdl_execute , r_fdl_suspendrequest , r_fdl_resumerequest or r_fdl_standby when fdl is in stand - by state . description: this function suspends an ongoing flash operation and brings fdl into stand - by state. the system can then change to special states (e.g. change power mode). function does not necessarily immediately suspend any flash operatio n, as suspend might be delayed by the device internal hardware or might not be supported at all (only erase and write are suspendable). so, the function r_fdl_standby tries to suspend the flash operation and returns r_fdl_busy as long as a flash operation is on - going. if suspend was not possible (e.g. blank check operation), r_fdl_busy is returned until the operation is finished normally. so, in order to be sure to have no flash operation on - going, the function must be called continuously until the function does no longer return r_fdl_busy or until a timeout occurred. after stand - by, it is mandatory to call r_fdl_wakeup to resume normal fdl operation again. the prescribed sequence in case of using r_fdl_standby / r_fdl_ wakeup is: ? any fdl command is in operati on ? call r_fdl_standby until it does no longer return r_fdl_busy ? put device in power sa v e (stand - by) mode ? device wake - up ? call r_fdl_wakeup ? continue with initial fdl command note: please consider not entering a power sa v e mode (e.g. deep stop mode) which resets the flash hardware, alter stack or library variables, because a resume of the previous operation is not possible afterwards. the library is not able to detect this failure. example: r_fdl_status_t fdlret_enu; r_fdl_request_t myreq_str_str ;
data flash access library - type t01, european release user interface (api) r01us0079ed0103 41 user manual /* start erase operation */ myreq_str_str.command_enu = r_fdl_cmd_erase; myreq_str_str.idx_u32 = 0; myreq_str_str.cnt_u16 = 4; myreq_str_str.accesstype_enu = r_fdl_access_user; r_fdl_execute (&myreq_str_str); ... do { fdlret = r_fdl_standby (); } while (r_fdl_busy == fdlret); if (r_fdl_ok != fdlret) { /* error handler */ } ... /* device enters power sa v e mode */ ... ... /* device recovers from power sa v e mode */ ... fdlret = r_fdl_wakeup (); if (r_fdl_ok != f dlret) { /* error handler */ } /* finish erase command */ while (myreq_str_str.status_enu == r_fdl_busy) { r_fdl_handler (); } if (r_fdl_ok != myreq_str_str.status_enu) { /* error handler */ while (1) ; } 4.4.3.4 r_fdl_wakeup outline: this function wakes - up the library from stand - by. interface: c interface r_fdl_status_t r_fdl_wakeup (void);
data flash access library - type t01, european release user interface (api) r01us0079ed0103 42 user manual arguments: parameters argument type access description none return value type description r_fdl_status_t ? r_fdl_ok operation finished successfully ? r_fdl_ err_ rejected wrong library handling flow: fdl is not in stand - by state pre - conditions: the library must be in stand - by mode . the hardware conditions (cpu frequency, voltage, etc...) must be restored to the state before issuing the stand - by request. post - conditions: none description: the main purpose of this function is to wake - up the library from the stand - by mode and resume f lash hardware . for more information see chapter 3.6 stand - by and wake - up functionality . example: see r_fdl_standby . 4.4.4 administration 4.4.4.1 r_fdl_getversionstring outline: this function returns the pointer to the null terminated library version string. interface: c interface (const uint8_t*) r_fdl_getversionstring (void); arguments: parameters argument type access description none
data flash access library - type t01, european release user interface (api) r01us0079ed0103 43 user manual return value type description const uint8_t * the library version is a string value in the following format: dh850t01xxxxxyzabcd pre - conditions: none post - conditions: none description: example: uint8_t * vstr = (uint8_t *)r_fdl_getversionstring (); figure 12 : version string d h 8 5 0 t 0 1 x x x x x y z a b c d o p t i o n a l c h a r a c t e r , i d e n t i f y i n g d i f f e r e n t e n g i n e e r i n g v e r s i o n s l i b r a r y v e r s i o n n u m b e r a . b c " e " f o r e n g i n e e r i n g v e r s i o n " v " f o r n o r m a l v e r s i o n c o d e d i n f o r m a t i o n a b o u t t h e u s e d m e m o r y / r e g i s t e r m o d e l . i f n o i n f o r m a t i o n i s c o d e d , t h e l i b r a r y i s a g e n e r i c l i b r a r y v a l i d f o r a l l m e m o r y / r e g i s t e r m o d e l s . c o d e d i n f o r m a t i o n a b o u t t h e s u p p o r t e d c o m p i l e r . i f n o i n f o r m a t i o n i s c o d e d , t h e l i b r a r y i s a s o u r c e c o d e l i b r a r y v a l i d f o r d i f f e r e n t c o m p i l e r s . l i b r a r y t y p e t 0 1 = t y p e 0 1 m c u s e r i e s n a m e h 8 5 0 = r h 8 5 0 f l a s h c o d e / d a t a l i b r a r y s = c o d e / d = d a t a
data flash access library - type t01, european release user interface (api) r01us0079ed0103 44 user manual 4.5 commands the following sub - chapters describe the flash operations that can be initiated and controlled by the library. in general, all fdl commands can be handled in the same way as illustrated in figure 13 : 1. the requester fills up the private request variable my_request (command def inition). 2. the requester tries to initiate the command execution by r_fdl_execute(&my_request) . 3. the requester has to call r_fdl_handler to proceed the fdl command execution as long the request is being processed (i.e. my_request.status_enu == r_fdl_busy ). 4. after finishing the command (i.e. my_request.status_enu != r_fdl_busy ) the requester has to analyse the status to detect potential errors. figure 13 : generic command execution flow s t a r t c o m m a n d e x e c u t i o n e n d o f c o m m a n d e x e c u t i o n f i l l r e q u e s t v a r i a b l e m y _ r e q u e s t r _ f d l _ e x e c u t e ( & m y _ r e q u e s t ) r _ f d l _ h a n d l e r ( ) e r r o r h a n d l i n g m y _ r e q u e s t . s t a t u s _ e n u ? < o t h e r > r _ f d l _ b u s y o t h e r u s e r a p p l i c a t i o n p r o c e s s i n g 1 2 3 4 m y _ r e q u e s t . s t a t u s _ e n u ? < o t h e r > r _ f d l _ o k
data flash access library - type t01, european release user interface (api) r01us0079ed0103 45 user manual 4.5.1 r_fdl_cmd_erase the erase command can be used to erase a number of flash blocks defined by a start block and the number of blocks. the members of the request structure given to r_fdl_execute are described in the following table: table 3 : request structure usage for erase c ommand structure member value description command_enu r_fdl_cmd_erase request a block erase operation bufaddr_u32 - not used idx_u32 {uint32_t number} number of the first block to be erased. flash blocks are defined by the erase granularity that is 64 bytes, e.g.: block 0: 0x00 ... 0x3f block 1: 0x40 ... 0x7f ... cnt_u16 {uint16_t number} numbers of blocks to erase accesstype_enu r_fdl_access_user / r_fdl_access_eel selects the flash pool in which the command will be able to operate. status_enu - this is an output member. it contains the status of the operation during and after the execution. possible values are described in the next table. the following table describes all possible status returns: table 4 : erase operation returned status status background and handling r_fdl_busy meaning o peration started successfully reason n o problems during execution remedy c all r_fdl_handler until the flash operation is finished, reported by the request structure status return value r_fdl_ok (1) meaning o peration finished successfully reason n o problems during execution remedy n othing r_fdl_suspended (1) meaning a n on - going flash operation was successfully suspended reason s uspend processing successfully finished remedy s tart another operation or resume the suspended operation r_fdl_err_parameter (2) meaning c urrent command is rejected reason wrong command parameters: ? access is made outside of physically available data flash ? command shall operate in user - pool but accesstype_enu is not r_fdl_access_user ? command shall operate in eel - pool but accesstype_enu is not r_fdl_access_eel ? cnt_u16 is 0 or it is too big
data flash access library - type t01, european release user interface (api) r01us0079ed0103 46 user manual status background and handling remedy r efrain from further flash operations and investigate in the root cause r_fdl_err_protection meaning c urrent command is rejected reason ? ? (2) meaning c urrent command is rejected reason an other operation is ongoing remedy request again the command when the preceding command has finished r_fdl_err_erase (1) meaning a t least one bit within the specified blocks is not erased reason hardware defect: one or more flash bits could not be erased completely remedy a flash block respectively the complete data flash should be considered as defect r_fdl_err_internal (1) meaning a library internal error occurred, which could not happen in case of normal application execution reason ? ? section 4.2 for details about (1) r_fdl_execute will never set this status code (2) r_fdl_handler will never set this status code 4.5.2 r_fdl_cmd_write the write command can be used to write a number of data words located in the ram into the data flash at the location specified by the virtual target address. note: it is not allowed to overwrite data, which means writing data to already partly or completely written flash area. please always erase the targeted area before writing into it. the members of the request structure given to r_fdl_execute are described in the following table: table 5 : request structure usage for write command structure membe r value description command_enu r_fdl_cmd_write request a write operation
data flash access library - type t01, european release user interface (api) r01us0079ed0103 47 user manual structure membe r value description bufaddr_u32 {uint32_t number} address of the buffer containing the source data to be written. idx_u32 {uint32_t number} the virtual start address for writing in d ata f lash aligned to word size (4 bytes). cnt_u16 {uint16_t number} number of words to write. accesstype_enu r_fdl_access_user / r_fdl_access_eel selects the flash pool in which the command will be able to operate. status_enu - this is an output member. it contai ns the status of the operation during and after the execution. possible values are described in the next table. the following table describes all possible status returns: table 6 : write operation returned status status background and handling r_fdl_busy meaning o peration started successfully reason n o problems during execution remedy call r_fdl_handler until the flash operation is finished, reported by the request structure status return value r_fdl_ok (1) meaning o peration finished successfully reason n o problems during execution remedy n othing r_fdl_suspended (1) meaning a n on - going flash operation was successfully suspended reason s uspend processing successfully finished remedy s tart another operation or resume the suspended operation r_fdl_err_parameter (2) meaning c urrent command is rejected reason wrong command parameters: ? access is made outside of physically available data flash ? command shall operate in user - pool but accesstype_enu is not r_fdl_access_user ? command shall operate in eel - pool but accesstype_enu is not r_fdl_access_eel ? cnt_u16 is 0 or it is too big ? flash writing address is not aligned with granularity (4 bytes) remedy refrain from further flash operations and investigate in the root cause r_fdl_err_protection meaning c urrent command is rejected
data flash access library - type t01, european release user interface (api) r01us0079ed0103 48 user manual status background and handling reason ? ? (2) meaning c urrent command is rejected reason an other operation is ongoing remedy request again the command when the preceding command has finished r_fdl_err_ write (1) meaning at least one data could not be written correctly reason ? user flow defect: tried to overwrite data ? (1) meaning a library internal error occurred, which could not happen in case of normal application execution reason ? ? section 4.2 for details about (1) r_fdl_execute will never set this status code (2) r_fdl_handler will never set this status code 4.5.3 r_fdl_cmd_blankcheck the blank check command can be used by the requester to check whether a specified amount of memory starting fro m a specified address is written . this command will stop at the first me mory location that is not erased with status r_fdl_err_blankcheck . note s : 1. on blank check fail, the cells are surely not blank. this might result from successfully written cells, but also from interru pted erase or write operations. on blank check pass, the cells are surely not written. this might result from successfully erased cells, 2. but also from interrupted erase or write operations. depending on the flash operations use case (e.g. eeprom emulation) it may be necessary to log 3. the flash operations results in order to be sure that flash cells are correctly written or erased. the way of logging depends on the use case (e.g. as part of a eeprom emulation concept)
data flash access library - type t01, european release user interface (api) r01us0079ed0103 49 user manual internally blankcheck operation is split into smaller operations every time the operation crosses a 4. 0x4000 bytes bou n dary. this means that time to suspend is not going to exceed the time to fully perform a blankcheck on 0x4000 bytes. the members of the request structure given to r_fdl_execute are described in the following table: table 7 : request structure usage for blank check command structure member value description command_enu r_fdl_cmd_blankcheck request a blank check operation bufaddr_u32 - not used idx_u32 {uint32_t number} input: the virtual start address for perform ing blank check in data flash. must be word (4 bytes) aligned. output: fail address in case of blank check error, unchanged if the operation finishes with r_fdl_ok . cnt_u16 {uint16_t number} number of words (4 b ytes) to check accesstyp e_enu r_fdl_access_user / r_fdl_access_eel selects the flash pool in which the command will be able to operate. status_enu - this is an output member. it contains the status of the operation during and after the execution. possible values are described in the next table. the following table describes all possible status returns: table 8 : blank check operation returned status status background and handling r_fdl_busy meaning o peration started successfully reason n o problems during execution remedy call r_fdl_handler until the flash operation is finished, reported by the request structure status return value r_fdl_ok (1) meaning o peration finished successfully reason n o problems during execution remedy n othing r_fdl_suspended (1) meaning a n on - going flash operation was successfully suspended reason s uspend processing successfully finished remedy s tart another operation or resume the suspended operation r_fdl_err_parameter (2) meaning c urrent command is rejected
data flash access library - type t01, european release user interface (api) r01us0079ed0103 50 user manual status background and handling reason wrong command parameters: ? ? accesstype_enu is not r_fdl_access_user ? accesstype_enu is not r_fdl_access_eel ? cnt_u16 is 0 or it is too big ? ? ? (2) meaning c urrent command is rejected reason an other operation is ongoing remedy request again the command when the preceding command has finished r_fdl_err_ blankcheck (1) meaning at least one bit within the specified blocks is not blank reason for any bit in the specified range the voltage level is below specification for a blank cell remedy remedy depends on the usage: ? ? ? r_fdl_cmd_blankcheck command fails when executed immediately after an erase operation on the same area r_fdl_err_internal (1) meaning a library internal error occurred, which could not happen in case of normal application execution reason ? ? section 4.2 for details about (1) r_fdl_execute will never set this status code
data flash access library - type t01, european release user interface (api) r01us0079ed0103 51 user manual (2) r_fdl_handler will never set this status code 4.5.4 r_fdl_cmd_read the read operation will read a certain address range in the data flash and copy the data to the specified target buffer. a higher level eeprom emulation library may want to read data flash addresses which are possibly not completely written or erased. reading those addresses would most probably result in an ecc error interrupt request which must be handled by the user application. this behaviour is usually not intended as an emulation library would have to deal with the errors. based on these considerations, the read operation of the fdl temporarily disables the interrupt generation fo r ecc errors . the status of ecc interrupt generation is restored when the operation is finished . errors detected during read operation are signalled to the user application by the request structure status_enu variable and idx_u32 variable. in case of singl e bit error the data read will be continued and the 1st occurrence of the ecc error will be returned. in case of double bit error, the read operation is stopped and the fail address is returned. in case of a previous single bit error detected, the fail add ress of the single bit error is overwritten. read command execution is synchronous to execution of r_fdl_execute function. therefore this command cannot be suspended and does not need to be processed by r_fdl_handler function. the members of the request st ructure given to r_fdl_execute are described in the following table: table 9 : request structure usage for read command structure member value description command_enu r_fdl_cmd_read request a read operation bufaddr_u32 {uint32_t number} d ata destination buffer address in ram . note: the buffer must be 32 bit aligned ! idx_u32 {uint32_t number} data flash v irtual address from where to read . must be word (4 bytes) aligned. cnt_u16 {uint16_t number} numbers of words (4 b ytes) to r ead accesstype_enu r_fdl_access_user / r_fdl_access_eel selects the flash pool in which the command will be able to operate. status_enu - this is an output member. it contains the status of the operation during and after the execution. possible values are d escribed in the next table. the following table describes all possible status returns: table 10 : read operation returned status status background and handling r_fdl_ok meaning o peration finished successfully reason n o problems during execution remedy n othing r_fdl_err_parameter meaning c urrent command is rejected
data flash access library - type t01, european release user interfa ce (api) r01us0079ed0103 52 user manual status background and handling reason wrong command parameters: ? ? accesstype_enu is not r_fdl_access_user ? accesstype_enu is not r_fdl_access_eel ? cnt_u16 is 0 or it is too big ? ? ? ? ? ? ? ? ?
data flash access library - type t01, european release user interface (api) r01us0079ed0103 53 user manual status background and handling remedy a multiple bit error can appear when caused by not completely written or erased flash. the reaction depends on the data handling concept. in case of expected c ompletely written flash a multiple bit error would mean loss of data. refrain from further flash operations and investigate in the root cause r_fdl_err_internal meaning a library internal error occurred, which could not happen in case of normal application execution reason ? ? section 4.2 for details
data flash access library - type t01, european release user interface (api) r01us0079ed0103 54 user manual the user shall take into consideration that the following registers are modified: 1. dferstc register is written to clear any errors in dffsterstr 2. dferrint register is backed up and cleared 3. dferrint register is restored figure 14 : handling of ecc error r egisters during read command r _ f d l _ c m d _ r e a d s t a r t s i n g l e b i t e r r o r r e a d e c c e r r o r s c l e a r e c c e r r o r s b a c k u p e c c i n t e r r u p t s t a t u s d i s a b l e e c c i n t e r r u p t s t a t u s r e a d d a t a f r o m d a t a f l a s h i n t o d e s t i n a t i o n b u f f e r d o u b l e b i t e r r o r l a s t r e a d a d d r e s s ? c l e a r e c c e r r o r s r e s t o r e e c c i n t e r r u p t s t a t u s y n s a v e a d d r e s s t h a t p r o v o k e d t h e e c c e r r o r n n r _ f d l _ c m d _ r e a d e n d y y s a v e a d d r e s s t h a t p r o v o k e d t h e e c c e r r o r 1 2 1 3
data flash access library - type t01, european release library setup and usage r01us0079ed0103 55 user manual chapter 5 library setup and usage this chapter contains important information about how to put the fdl into operation and how to integrate it into your application. please read this chapter carefully and also especially chapter 6 cautions in orde r to avoid problems and misbehaviour of the library. before integrating the library into your project however, please make sure that you have read and understood how the fdl works and which basic concepts are used (see chapter 2 architecture and chapter 3 functional specifications ). 5.1 obtaining the library the fdl is provided by means of an instal ler via the renesas homepage at http://www.renesas.eu/update please follow the instructions of the installer carefully. please ensure to always work on the latest version of the library. 5.2 file structure the library is delivered as a complete compilable sample project which contains the fdl and in addition an application s ample to show the library implementation and usage in the target application. the delivery package contains dedicated directories for the library, containing the source and the header files. 5.2.1 overview the following picture contains the library and the appl ication related files: figure 15 : file structure of library and sample application l i b r a y r _ f d l _ . . . . a / l i b f a l _ . . . c f a l _ . . . c r _ f d l _ . . . . c p r e c o m p i l e d l i b r a r y s o u r c e c o d e l i b r a r y u s e r f d l _ d e s c r i p t o r . c f a l _ . . . c f a l _ . . . c m a i n . c d e s c r i p t o r s p a s s e d t o t h e l i b r a r y s o u r c e c o d e a p p l i c a t i o n r _ f d l . h f d l _ c f g . h l i b r a r y f i l e s C f i x , m a y n o t b e t o u c h e d b y t h e u s e r l i b r a r y p r e - c o m p i l e c o n f i g u r a t i o n ( o n l y o n s o u c e c o d e d e l i v e r y ) C f i l e n a m e f i x , f i l e c o n t e n t u s e r c o n f i g u r a b l e a p p l i c a t i o n ( u s e r ) c o d e C c o m p l e t e l y i n t h e h a n d o f t h e u s e r l i b r a r y c o n f i g u r a t i o n a p i d e c l a r a t i o n f d l _ d e s c r i p t o r . h
data flash access library - type t01, european release library setup and usage r01us0079ed0103 56 user manual the library must be configured for compilation. the file fdl_cfg.h contains defines for that. as it is included by the library source files, t he file contents may be modified by the user, but the file name may not. these files reflect an example, how the library descriptor variable can be built up and passed to the function r_fdl_init for run - time configuration. the structure of the descriptor i s defined in r_fdl_types.h which needs to be included in the user application. the value definition should be done in the file fdl_descriptor.h . the constant variable definition and value assignment should be done in the file fdl_descriptor.c . if adding th e files r_fdl_ descriptor.c / h to the application, only the file fdl_descriptor.h needs to be adapted by the user, while fdl_descriptor.c may remain unchanged. for usage please refer to chapter 4.2 run - time configuration . 5.2.2 delivery package directory structure and files the following table contains all files installed by the library installer: ? files in red belong to the build environment, controlling the compile, link and target build process ? files in blue belong to the sample applica tion ? files in green are description files only ? files in black belong to the f d l table 11 : file structure of the fdl package file description release.txt library package release notes. /make gnupubliclicense.txt gnu make utility license file readme.txt extra information for source code of gnu make make.exe minimal installation of gnu make utility libiconv2.dll libintl3.dll setup.exe gnu make installer package < installation_folder>// build.bat batch file to build the fd l sample application clean.bat batch file to clean the fd l sample application makefile make file that controls the build and clean process /< device_name>//sample dr7f701035_startup.850 (2) device and compiler specific start - up code cstart.asm (2) dr7f701035.ld (2) compiler specific linker directives dr7f701035.dir (2) dr7f701035_0.h (2) dr7f701035_irq.h (2) io_macros_v2.h (2) definitions of io registers , interrupt and exceptions vector table, for RH850 device iodefine.h (2) vecttbl.asm (2)
data flash access library - type t01, european release library setup and usage r01us0079ed0103 57 user manual file description eel_cfg.h (1) eel pre - compile definitions eel_descriptor.c (1) eel descriptor used in the sample application eel_descriptor.h (1) sample app.h sample application code sample app_control.c sample app_main.c fdl_cfg.h fdl pre - compile definitions fdl_descriptor.c fdl descriptor used in the sample application fdl_descriptor.h fdl_user.c user defined code for handling interrupts and library pre - initialization fdl_user.h target.h initialization code for target microcontroller r_typedefs.h c types used by f d l library < installation_folder>///sample/eel (1) r_eel.h (1) eel api definitions r_eel_mem_map.h (1) s ection mapping definitions r_eel_types.h (1) user interface type definitions, error and status codes //< compiler>/sample/eel/lib (1) r_eel_basic_fct.c (1) eel main source code r_eel_user_if.c (1) r_eel_global.h (1) global variables and settings ///sample/fdl r_fdl.h f d l api definitions r_fdl_mem_map.h s ection mapping definitions r_fdl_types.h user interface type definitions , error and status codes ///sample/fdl/lib r_fdl_env.h internal f d l definitions r_fdl_global.h global variables and settings r_fdl_hw_access.c f d l main source code r_fdl_user_if.c (1) these files are not available if the eel layer is not part of the delivered package (2) file names are dependent on the chosen device. shown filenames are valid for f1l devices
data flash access library - type t01, european release library setup and usage r01us0079ed0103 58 user manual 5.3 library resources 5.3.1 linker sections the following sections are related to the data flash access library and need to be defined in the linker file (please see sample linker directive file for an example): data sections: ? r_fdl_data this section contains all fdl internal variables. it can be located either in internal or external ram. code sections: ? r_fdl_const this section contains library internal constant data. it c an be loca ted anywhere in the code flash. ? r_fdl_text fdl code section containing the library code . it c an be located any where in the code flash. 5.3.2 stack and data buffer the fdl utilizes the same stack as specified in the user application. it is the developers duty to reserve enough stack for the operation of both, user application and fdl. with source code library it is not possible to give an exact value for stack consumption. however, an estimate value for the fdl library is : 2 68 b ytes for ghs compiler and 316 bytes for renesas compiler . the data buffer used by the fdl refers to the ram ar ea in which data is located that is to be written into the data flash. this buffer needs to be all ocated and managed by the user. note: in order to allocate the stack and data buffer to a user - specified address, please utilize the link directives of your f ramework. 5.4 misra compliance the fdl code has been tested regarding misra tm compliance. the used tool is the qa c tm source code analyzer which tests against the misra tm 2004 standard rules. note: "misra" is a registered trademark of mira ltd, held on b ehalf of the misra consortium. qa c is a registered trademark of programming research ltd. 5.5 sample application it is very important to have theoretic background about the data flash and the fdl in order to successfully implement the library into the user application. therefore it is important to read this user manual in advance. the best way, after initial reading of the user manual, will be testing the fdl application sample. after a first compile run, it will be worth playing around with the library in the debugger. by that you will get a feeling for the source code files and the wor king mechanism of the library. after this exercise it might be easier to understand and follow the recommendations and considerations of this document.
data flash access library - type t01, european release library setup and usage r01us0079ed0103 59 user manual note: before the first compile run, the compiler path must be configured in the m akefile of the sample application: set the variabl e compiler_install_dir to t he correct compiler directory. 5.6 library configuration before using the data flash access library, the library has to be configured and adapted to a certain degree in order to fit the requirements of the user application. for information about configuration settings and handling, please refer to chapter 4.2 run - time configuration . 5.7 basic reprogramming flow the following flow chart shows the basic reprogramming flow for a certain data flash range.
data flash access library - type t01, european release library setup and usage r01us0079ed0103 60 user manual fi gure 16 : basic reprogramming flow r e p r o g r a m m i n g s t a r t f d l _ i n i t r e p r o g r a m m i n g e n d ( s u c c e s s ) r _ f d l _ e x e c u t e ( & r e q ) r _ f d l _ b u s y = = r e q . s t a t u s _ e n u n y r _ f d l _ h a n d l e r u s e r c o d e e x e c u t i o n c o n f i g u r e r e q u e s t s t r u c t u r e r e q ( r _ f d l _ c m d _ e r a s e ) r _ f d l _ e x e c u t e ( & r e q ) r _ f d l _ b u s y = = r e q . s t a t u s _ e n u n y r _ f d l _ h a n d l e r u s e r c o d e e x e c u t i o n c o n f i g u r e r e q u e s t s t r u c t u r e r e q ( r _ f d l _ c m d _ w r i t e ) a l l d a t a w r i t t e n ? y n r _ f d l _ o k = = r e q . s t a t u s _ e n u y n r _ f d l _ o k = = r e q . s t a t u s _ e n u y n r e p r o g r a m m i n g e n d ( e r r o r h a n d l e r ) r e p r o g r a m m i n g e n d ( e r r o r h a n d l e r ) f l a s h e r a s e f l o w f l a s h w r i t e f l o w
data flash access library - type t01, european release library setup and usage r01us0079ed0103 61 user manual error treatment of the fdl functions themselves is not detailed described in the flow charts for simplification reasons. for details on enabling or disabling access to the data flash, refer to the user's manual for the hardware. an example is given by the sample application, file sample_app_main.c , functions fdl_open and fdl_close . 5.8 r_fdl_handler calls once initiated fdl operations need to be driven forward by successive handler calls. the frequenc y of these handler calls does have an impact on the fdl operation performance and needs to be adapted to the target application. in the following, different approaches for calling the r_fdl_handler are compared with respect to their advantages and disadvan tages: ? calling r_fdl_handler repeatedly after starting an operation execution: this approach is also utilized in most of the code examples you can find in this manual. typically realized in a loop waiting for the operation status not to be busy anymore, th is approach results in the best fdl operation performance. however, the cpu is fully loaded and blocked for other tasks as long as the fdl operation is being executed. ? calling r_fdl_handler in a timed task: by calling the r_fdl_handler periodically, fdl co mmands can be driven forward while other tasks are processed by the cpu. the period between the status check calls can have significant impact on the fdl operation performance. shorter calling intervals result in better fdl performance, but also increase t he cpu load by the fdl. due to this trade off, a general advice for the calling interval cannot be given. it needs to be analysed and tailored individually f or each target application. ? calling r_fdl_handler in the idle task: if it is ensured that the idle task is called often enough, this method might result in a good fdl performance, as the handler can be called continuously. however, this approach is not deterministic in case of a high cpu l oad by the application itself. due to the individual requirements of each application, a general advice for selecting a strategy to call the r_fdl_handler cannot be given. please also consider that mixtures of the above mentioned approaches can be meaningful dep ending on the target scenario. note: when evaluating concepts for calling the r_fdl_handler , please be aware that all fdl functions are not re - entrant. that means it is not allowed to call an fdl function from interrupt service routines while another fdl function is already running.
data flash access library - type t01, european release cautions r01us0079ed0103 62 user manual chapter 6 cautions before starting the development of an application using the fdl, please carefully read and understand the following cautions: 1. cpu operating frequency configuration: correct frequency configuration is essential for flash programming quality and stability. w rong configuration could lead to loss of data retention or flash operation fail. the limits for cpu frequency are device dependent. please consult device m anual for correct range . if the cpu frequency is a fractional value, round up the value to the neares t integer. do not change power mode (voltage or cpu clock) while fdl is performing a data flash operation. if power mode must change the user can: ? put current operation into stand - by mode and wait until hardware conditions are restored ? wait until operation s are no longer busy or ? reinit ialize the library with proper cpu frequency value 2. cpu mode : the initialization function r_fdl_init must be executed in cpu supervisor mode (register bit psw.um = 0). 3. function re - entrancy: all functions are not re - entrant. so, re - entrant calls of any f d l function must be avoided. 4. task switch, context change, synchronization between functions: each function depends on global available information and is able to modify this information. in order to avoid synchronization problems, it is necessary that at any time only one f d l function is executed. so, it is not allowed to start an f d l function, then switch to another task context and execute another fd l function while the last one has not finished. entering power sa v e (stand - by) mode: 5. entering power sa v e mode is not allowed at all during on - going data flash operations. use r_fdl_standby or wait until operations are no longer busy. different power sa v e (stand - by) modes: 6. other power sa v e modes than halt will result in flash hardware internal data loss. so, dont enter power sa v e modes except halt when further fdl operations are intended after wake - up. if entering other modes, the fdl need to be re - initialized by r_fdl_init . 7. initialization: the fdl library initialization by means of c alling r_fdl_init must be performed before calling most of the library functions. exception is r_fdl_getversionstring function that can be called anytime. critical section handling : 8. the r_fdl_init function temporarily disables code flash. during this time, since the code flash is not available, the library is executing code from internal ram (allocated space on stack). please ensure that : ? code execution is done from other locations (e.g. internal ram). ? no access to code flash is allowed, e.g. by j ump to in terrupt/exception functions, direct code flash read/execution from the cpu, dma accesses to code flash . the user can configure the provided callback macro functions in fdl_cfg.h . , in order to handle e.g.
data flash access library - type t01, european release cautions r01us0079ed0103 63 user manual interrupt & e xception disable, dma, ... . the sample application provides examples on how to disable and restore interrupts and exceptions using the callback routines . 9. interrupted flash operations: in case of flash modification operation (erase / write) interruption, the electrical conditions of the affected flash range (flash block on erase, flash write unit on write) get undefined. it is impossible to give a statement on the read value after the interruption. furthermore, the resulting read value is not reliable; the electrical margin for the sp ecified data retention may not be given. in such case, erase and re - write the affected flash block(s) to ensure data integrity and retention. 10. write operation: before executing a write operation, please make sure the given address range is erased. 11. reading d ata flash: data flash on RH850 devices is made with differential cells for storage. this means that reading erased data flash areas directly (bypassing fdl) will produce undefined data with a tendency to the previously written data and it will most probabl y cause ecc error exceptions. to avoid this exceptions use r_fdl_cmd_read command . dma transfers from data flash are permitted, but need to be synchronized with the fd l . during command execution data flash is not available. any direct read during command e xecution will result in invalid dat a therefore it must be avoided. 12. dual operation: it is not possible to modify the code flash in parallel to a modification of the data flash or vice versa due to shared hardware resources. 13. reusing the request command: do not change the content of the request structure while an fdl command is operating because the library may crash or data loss can occur. multiple requests, each using different request structures, do not have these adverse effects. workload and supervision: 14. it is recommended to supervise the fdl operations and functions execution by timeout supervision (e.g. timer , counter, watchdog, etc. ). in addition, the user of the library should evaluate the time necessary to perform a certain operation and divide long lasting operation s to meet real - time system specifications . suspend and stand - by nesting: 15. it is not always possible to nest suspend and/or stand - by. e.g.: ? any operation ? susp end ? suspend C is not possible. ? any operation ? stand - by ? stand - by C is n ot possible. ? any operation ? stand - by ? suspend C is not possible. ? write or erase ? suspend ? era se operation C is not possible ? any operation ? suspend ? other operation ? suspend C is not possible ? write operation ? suspend ? other write operation C is not po ssible it is recommended to avo id nesting as much as possible. stand - by: 16. do not continue fdl functions execution or start execution of any other function than r_fdl_getversionstring , r _fdl_wakeup or r_fdl_init when t he library is in stand - by mode. data ali gnment: 17. data flash blocks are aligned to 64 bytes and data flas h words are aligned to 4 bytes.
data flash access library - type t01, european release cautions r01us0079ed0103 64 user manual RH850 devices also add alignment restrictions for types lar ger than 8 bits . please consult device hardware manual for details . precompile options 18. the user must not use any pre - compile co n f i g uration options that are not documented in present manual. supported devices 19. the RH850 fdl library is supported on 3 device families at the moment of writing of this manual. these families are e1x, f1x , p1x and r1x (where x can be any lett er depending on power consumption, peripherals, etc). further device families may be added in the future.
data flash access library - type t01, european release revision history r01us0079ed0103 65 user manual revision history chapter page description rev. 1.03: initial released document version
r01us0079ed0103 data flash access library

▲Up To Search▲

Price & Availability of RH850

	To Download RH850 Datasheet File
If you can't view the Datasheet, Please click here to try to view without PDF Reader .